<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>drand48</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_003_160">&nbsp;</a>NAME</h4><blockquote>
drand48, erand48, jrand48, lcong48, lrand48, mrand48, nrand48, seed48, srand48
- generate uniformly distributed pseudo-random numbers
</blockquote><h4><a name = "tag_000_003_161">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="stdlib.h.html">stdlib.h</a>&gt;

double drand48(void);
double erand48(unsigned short int <i>xsubi</i>[3]);
long int jrand48(unsigned short int <i>xsubi</i>[3]);
void lcong48(unsigned short int <i>param</i>[7]);
long int lrand48(void);
long int mrand48(void);
long int nrand48(unsigned short int <i>xsubi</i>[3]);
unsigned short int *seed48(unsigned short int <i>seed16v</i>[3]);
void srand48(long int <i>seedval</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_003_162">&nbsp;</a>DESCRIPTION</h4><blockquote>
This family of functions generates pseudo-random numbers using
a linear congruential algorithm and 48-bit integer arithmetic.
<p>
The
<i>drand48()</i>
and
<i>erand48()</i>
functions
return non-negative, double-precision, floating-point values,
uniformly distributed over the interval [0.0 , 1.0].
<p>
The
<i>lrand48()</i>
and
<i>nrand48()</i>
functions
return non-negative, long integers, uniformly distributed over the
interval [0,2<small><sup>31</sup></small>].
<p>
The
<i>mrand48()</i>
and
<i>jrand48()</i>
functions
return signed long integers uniformly distributed over the
interval [-2<sup><small>31</small></sup>,2<sup><small>31</small></sup>].
<p>
The
<i>srand48()</i>,
<i>seed48()</i>
and
<i>lcong48()</i>
are initialisation entry points, one of which should be invoked before
either
<i>drand48()</i>,
<i>lrand48()</i>
or
<i>mrand48()</i>
is called.
(Although it is not recommended practice,
constant default initialiser values will be supplied automatically if
<i>drand48()</i>,
<i>lrand48()</i>
or
<i>mrand48()</i>
is called without a prior call to an initialisation entry point.)
The
<i>erand48()</i>,
<i>nrand48()</i>
and
<i>jrand48()</i>
functions do not require an initialisation entry point to be called first.
<p>
All the routines work by generating a sequence of 48-bit integer
values, X<small><sub>i</sub></small> , according to the linear congruential formula:
<pre>
<dl compact><dt> <dd>
X<small><sub>n+1</sub></small> = (aX<small><sub>n</sub></small> + c)<small><sub>mod m</sub></small>&nbsp;&nbsp;&nbsp;n&gt;= 0
</dl>
</pre>
<p>
The parameter <i>m</i> = 2<small><sup>48</sup></small>; hence 48-bit integer arithmetic is
performed.
Unless
<i>lcong48()</i>
is invoked, the multiplier value <i>a</i> and the addend value <i>c</i>
are given by:
<pre>
<dl compact><dt> <dd>
<i>a</i> = 5DEECE66D<small><sub>16</sub></small> = 273673163155<small><sub>8</sub></small>

<i>c</i> = B<small><sub>16</sub></small> = 13<small><sub>8</sub></small>
</dl>
</pre>
<p>
The value returned by any of the
<i>drand48()</i>,
<i>erand48()</i>,
<i>jrand48()</i>,
<i>lrand48()</i>,
<i>mrand48()</i>
or
<i>nrand48()</i>
functions
is computed by first generating the next 48-bit X<small><sub>i</sub></small> in the sequence.
Then the appropriate number of bits, according to the type of data item
to be returned, are copied from the high-order (leftmost) bits of X<small><sub>i</sub></small>
and transformed into the returned value.
<p>
The
<i>drand48()</i>,
<i>lrand48()</i>
and
<i>mrand48()</i>
functions
store the last 48-bit X<small><sub>i</sub></small> generated in an internal buffer;
that is why they must be initialised prior to being invoked.
The
<i>erand48()</i>,
<i>nrand48()</i>
and
<i>jrand48()</i>
functions require the calling program to provide storage for the
successive X<small><sub>i</sub></small> values in the array
specified as an argument when the functions are invoked.
That is why these routines do not have to be initialised; the calling
program merely has to place the desired initial
value of X<small><sub>i</sub></small> into the array and pass it as an argument.
By using different
arguments,
<i>erand48()</i>,
<i>nrand48()</i>
and
<i>jrand48()</i>
allow separate modules of a large program to generate several
<i>independent</i>
streams of pseudo-random numbers, that is the sequence of numbers
in each stream will
<i>not</i>
depend upon how many times the routines are called to generate
numbers for the other streams.
<p>
The initialiser function
<i>srand48()</i>
sets the high-order 32 bits of X<small><sub>i</sub></small> to the low-order 32
bits contained in its argument.
The low-order 16 bits of X<small><sub>i</sub></small> are set to the arbitrary value
330E<small><sub>16</sub></small> .
<p>
The initialiser function
<i>seed48()</i>
sets the value of X<small><sub>i</sub></small> to the 48-bit value specified in the
argument array.
The low-order 16 bits of X<small><sub>i</sub></small> are set to the low-order 16 bits of
<i>seed16v[0]</i>.
The mid-order 16 bits of X<small><sub>i</sub></small> are set to the low-order 16 bits of
<i>seed16v[1]</i>.
The high-order 16 bits of X<small><sub>i</sub></small> are set to the low-order 16 bits of
<i>seed16v[2]</i>.
In addition, the previous value of X<small><sub>i</sub></small> is copied into a 48-bit
internal buffer, used only by
<i>seed48()</i>,
and a pointer to this buffer is the value returned by
<i>seed48()</i>.
This returned pointer, which can just be ignored if not needed, is useful
if a program is to be restarted from a given point at some future time
- use the pointer to get at and store the last X<small><sub>i</sub></small> value, and
then use this value to re-initialise via
<i>seed48()</i>
when the program is restarted.
<p>
The initialiser function
<i>lcong48()</i>
allows the user to specify the initial X<small><sub>i</sub></small>, the multiplier
value <i>a</i>, and the addend value <i>c</i>.
Argument array elements
<i>param</i>[<i>0-2</i>]
specify X<small><sub>i</sub></small>,
<i>param</i>[<i>3-5</i>]
specify the multiplier <i>a</i>, and
<i>param</i>[<i>6</i>]
specifies the 16-bit addend <i>c</i>.
After
<i>lcong48()</i>
is called, a subsequent call to either
<i>srand48()</i>
or
<i>seed48()</i>
will restore the standard multiplier and addend values, <i>a</i> and <i>c</i>,
specified above.
<p>
The
<i>drand48()</i>,
<i>lrand48()</i>
and
<i>mrand48()</i>
interfaces need not be reentrant.
</blockquote><h4><a name = "tag_000_003_163">&nbsp;</a>RETURN VALUE</h4><blockquote>
As described in the DESCRIPTION above.
</blockquote><h4><a name = "tag_000_003_164">&nbsp;</a>ERRORS</h4><blockquote>
No errors are defined.
</blockquote><h4><a name = "tag_000_003_165">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_003_166">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_003_167">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_003_168">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="rand.html">rand()</a></i>,
<i><a href="stdlib.h.html">&lt;stdlib.h&gt;</a></i>.
</blockquote><h4>DERIVATION</h4><blockquote>
Derived from Issue 1 of the SVID.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>

